# VISTA Link AI 智能体技术架构与实施方案
> 文档定位：研发、架构、安全、运维和技术评审用的实施文档。拆分日期：2026-08-23业务与产品主文档：[《VISTA Link AI 智能体业务与产品解决方案》](./VISTA_Link_AI智能体综合解决方案_基于项目多文档.md)编号说明：为保持与原综合稿、PRD 讨论和项目内既有引用一致，本技术文档沿用原 §11—§19 编号。范围说明：本文只负责数据对象、Agent 工具、多租户架构、模型供应商、集成、容量、可靠性、安全和日本合规实现；客户阶段、接待方法、销售流程、MVP 与业务边界以业务主文档为准。   

---

## 11\. 核心业务对象

### 11.1 正式 PRD 对象
- 租户、项目、成员、角色、权限；
- 客户、素材、页面、页面版本、Widget；
- 固定链接、客户专属访问地址、访问会话；
- 行为事件、客户追踪、营销统计；
- AI 会话、任务、草稿、确认与审计。

### 11.2 建议新增对象

| 对象 | 用途 | 状态 |
|------|------|------|
| reception\_playbook | 项目级客群标准方案；保存客群定义、默认内容包、标准提问、必讲项、风险项和版本 | 【采用，需改 PRD】 |
| content\_package | 按项目概况、交通、户型、眺望日照、公共设施、价格费用等主题组织当前有效内容 | 【采用，需改 PRD】 |
| acquisition\_source | 官网、SUUMO、广告、介绍、资料请求、物件登记、来场预约、线上咨询等反响来源及原始引用 | 【采用，需改 PRD】 |
| customer*engagement*stage | 反响、初次接触、个体追客、申请及结果；保存变更原因、确认人、时间和依据 | 【采用，需改 PRD】 |
| standard*nurture*plan | 反响及未商谈化客户使用的项目标准页面、通知、预约提醒和内容更新；不包含个体推断 | 【采用，需改 PRD】 |
| customer\_condition | 客户条件、来源、确认和历史 | 【采用，需改 PRD】 |
| visit\_session | 区分第几次接待和现场模式 | 【采用，需改 PRD】 |
| first*contact*plan | 资料请求、首次咨询/首次接待所选择的客群标准方案及版本；不是客户已确认属性 | 【采用，需改 PRD】 |
| customer*followup*plan | 销售确认客户进入个体追客后，根据明确反馈、有效行为和历史生成的个体跟进、页面或复访方案 | 【采用，需改 PRD】 |
| visit\_preparation | 个体追客客户的复访准备快照、个体依据、AI 建议和销售确认版本 | 依据正式 AI 能力细化 |
| visit\_adjustment | 保存现场相对客群标准方案或个体复访方案的增加、跳过、替换及理由 | 【采用，需改 PRD】 |
| visit\_summary | 接待后纪要草稿、原方案与实际接待差异、人工确认版本 | 依据正式 AI 能力细化 |
| unresolved\_question | 未解决问题、负责人、状态和期限 | 【采用，需改 PRD】 |
| share\_record | 每次分享、渠道、活动和客户关系 | 【采用，需改 PRD】 |
| consent\_record | 通信同意、退订、渠道和有效期 | 【采用，需改 PRD】 |
| message / message\_version | SMS 草稿、确认版本和实际发送版本 | 【采用，需改 PRD】 |
| message\_delivery | 供应商状态、送达、失败和重试 | 【采用，需改 PRD】 |
| appointment\_reference | Link 与预约权威系统之间的映射 | 【采用，需改 PRD】 |
| business*outcome*reference | 到访/认购/签约等必要结果引用；只保存必要结果 | 【采用，需改 PRD】 |
| ai\_conclusion | 结论、证据、版本、置信度和失效 | 【正式 PRD】 |
| action\_request | Agent 提出的结构化动作 | 【正式 PRD】 |
| approval\_decision | 确认、修改、驳回、审核 | 【正式 PRD】 |
| attribution\_result | 规则、窗口、触点和分配结果；后置建设 | 【采用，需改 PRD】 |
| roi\_result | 公式、数据范围、币种和结果；后置建设 | 【采用，需改 PRD】 |
| intent\_score | 特征、版本、解释、衰减和纠正；后置建设 | 【采用，需改 PRD】 |

---

## 12\. Agent 工具设计

### 12.1 工具原则
- 工具只表达业务动作，不提供“执行任意 SQL”或“调用任意 URL”；
- 所有对象 ID 由服务端再次按租户、项目和权限校验；
- 写入工具要求版本号或幂等键；
- 对外动作保存确认人、确认版本和实际执行结果；
- 关键事实必须调用权威服务，不让模型生成。

### 12.2 当前 PRD 内工具示例
```text
get_current_context()
search_customers(project_id, filters)
get_customer_detail(customer_id)
get_customer_engagement_stage(customer_id)
get_customer_activity(customer_id, source_type)
search_assets(project_id, query)
get_page(page_id, version)
compose_page_draft(customer_id, asset_ids)
save_page_draft(draft_id, expected_version)
publish_page(page_id, expected_version)
generate_visit_preparation(customer_id)
generate_visit_summary(visit_session_id)
get_dashboard_metrics(project_id, metric_definition_version)
```

### 12.3 扩展工具示例
```text
list_reception_playbooks(project_id, customer_segment)
select_first_contact_playbook(customer_id_optional, playbook_id, expected_playbook_version)
create_standard_nurture_plan(customer_id, playbook_id, consent_scope, expected_version)
qualify_customer_for_individual_followup(customer_id, confirmed_facts, next_step, expected_stage_version)
create_customer_followup_plan(customer_id, evidence_ids, expected_version)
create_revisit_preparation(customer_id, followup_plan_id, expected_version)
record_onsite_adjustment(visit_session_id, changes, reason, idempotency_key)
finalize_visit_summary(visit_session_id, confirmed_changes, expected_version)
create_share_record(customer_id, page_version, channel, campaign_id)
create_sms_draft(customer_id, template_id, page_version)
send_approved_message(action_id, confirmation_token)
query_available_slots(project_id, date_range)
hold_appointment_slot(customer_id, slot_id, idempotency_key)
confirm_appointment(hold_id, confirmation_token)
calculate_attribution(project_id, window, approved_model_version)
calculate_roi(project_id, period, metric_definition_version)
refresh_intent_score(customer_id, scoring_version)
```

Agent 只负责决定“建议调用哪个工具并准备参数”；Link 的策略网关决定“当前用户是否可以调用、是否需要确认、是否满足规则”；业务服务负责实际写入和外部调用。
```mermaid
sequenceDiagram
    participant U as 销售用户
    participant UI as 浏览器AI面板
    participant A as Agent运行层
    participant P as Link策略网关
    participant S as Link业务服务
    participant X as 外部系统

    U->>UI: 提出任务
    UI->>A: 发送当前项目和对象上下文
    A->>A: 生成结构化工具调用候选
    A->>P: action_request
    P->>P: 校验权限、版本、风险和幂等
    alt 需要人工确认
        P-->>UI: 返回确认卡和变更对比
        UI-->>U: 展示依据与影响
        U->>UI: 确认、修改或驳回
        UI->>P: approval_decision
    else 命中允许规则
        P->>P: 记录预授权命中依据
    end
    P->>S: 执行强类型业务动作
    S->>X: 发送、发布或预约调用
    X-->>S: 权威执行结果
    S-->>A: 工具结果
    A-->>UI: 解释结果和下一步
    UI-->>U: 展示完成状态与审计入口
```

---

## 13\. 浏览器、多租户与服务端架构

### 13.1 总体结构
```mermaid
flowchart TB
    UI["浏览器中的 Link 与 AI 面板"] --> GW["Agent Gateway"]
    GW --> CTX["上下文构建服务"]
    GW --> POLICY["工具与策略网关"]
    GW --> TASK["任务与会话服务"]
    TASK --> QUEUE["任务队列"]
    QUEUE --> WORKER["Agent Workers"]
    WORKER --> MODEL["模型网关 / OpenAI / 其他模型"]
    WORKER --> POLICY
    POLICY --> LINK["Link 业务服务"]
    LINK --> DB["租户与项目数据"]
    LINK --> CONNECT["SMS / LINE / 日历 / CRM / 预约连接器"]
    GW --> AUDIT["AI与业务审计"]
```

### 13.2 浏览器负责
- 呈现当前上下文；
- 收集用户输入和附件；
- 展示流式进度、依据、草稿、差异和确认卡；
- 允许取消、重试、修改和人工接管；
- 浏览器关闭后能够恢复任务状态。

### 13.3 服务端负责
- 身份认证、租户/项目/对象权限；
- 上下文最小化和敏感字段脱敏；
- 模型选择、提示和知识检索；
- 工具参数校验、风险分级和确认；
- 长任务、重试、幂等和检查点；
- 外部系统调用、结果回写和审计；
- 配额、成本、限流和公平调度。

### 13.4 多租户强制规则

每次 AI 请求和工具调用必须包含并由服务端验证：
```text
tenant_id
project_id
user_id
role_ids
object_type
object_id
permission_snapshot_version
request_id
```

数据库查询不得只依赖模型返回的 ID。所有查询都要附加当前租户与项目范围；项目切换后，旧对话不能继续无提示地使用旧项目上下文。

### 13.5 任务模型

浏览器会话不等于任务。建议状态：
```mermaid
stateDiagram-v2
    [*] --> Created
    state "已创建" as Created
    state "排队中" as Queued
    state "运行中" as Running
    state "等待用户补充" as WaitingUser
    state "等待审批" as WaitingApproval
    state "执行业务动作" as Executing
    state "已完成" as Completed
    state "失败" as Failed
    state "已取消" as Cancelled
    state "已过期" as Expired

    Created --> Queued
    Queued --> Running
    Running --> WaitingUser: 缺少必要信息
    Running --> WaitingApproval: 需要确认或审核
    WaitingUser --> Queued: 用户补充后继续
    WaitingApproval --> Executing: 通过
    WaitingApproval --> Cancelled: 驳回或取消
    Running --> Executing: 无需审批
    Executing --> Completed
    Running --> Failed
    Executing --> Failed
    Created --> Cancelled
    Queued --> Expired: 超过有效期
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]
    Expired --> [*]
```

长任务保存检查点，浏览器刷新或关闭后可以重新连接。写入动作不能因为前端重复提交而重复执行。

---

## 14\. 模型与供应商方案

### 14.1 模型中立

业务对象、工具、权限、确认和审计由 Link 定义，不绑定某一家模型。OpenAI、DeepSeek 或未来其他模型只处于推理与编排层。

### 14.2 路由原则
```mermaid
flowchart TD
    A["收到AI任务"] --> B{"确定规则能完成吗"}
    B -->|能| C["使用规则或数据库查询"]
    B -->|不能| D{"任务类型"}
    D -->|分类 / 提取 / 整理| E["低成本模型"]
    D -->|复杂摘要 / 比较 / 草稿| F["主模型"]
    D -->|高敏感或禁止外发| G["指定区域 / 私有模型 / 人工"]
    E --> H{"输出与工具校验通过吗"}
    F --> H
    G --> H
    H -->|通过| I["进入证据、确认和业务流程"]
    H -->|模型失败| J["备用模型"]
    H -->|数据或规则失败| K["安全降级或人工处理"]
    J --> H
```

### 14.3 API Key 管理
- Key 只保存在服务端密钥系统；
- 测试与生产分离；
- 按租户、项目、模型和功能设置额度；
- 日志不出现完整 Key、手机号和客户敏感信息；
- 支持平台统一 Key、企业自带 Key 和企业专属部署；
- 普通销售界面不出现“选择模型”或“填写 API Key”。

### 14.4 Codex/DeepSeek Harness 的正确关系

可以参考 Codex 或 DeepSeek Harness 的“理解上下文—制定步骤—调用工具—返回结果”模式，但 VISTA Link 需要构建自己的：
- 房地产业务对象；
- 租户和项目权限；
- 页面、访问、客户、发送和预约工具；
- 确认与审计；
- 浏览器端任务体验。

不能把通用编码智能体直接暴露给企业客户，更不能让其直接接触操作系统或数据库。

---

## 15\. OpenAI 官方文档与 Link 方案对应章节
> 核对日期：2026-08-22。OpenAI API、模型、价格、限额和数据政策会更新；开发启动和上线前应再次核对官方文档。采用原则：OpenAI 提供模型、推理、工具调用和托管工具能力；VISTA Link 仍负责租户、项目、权限、业务状态、人工确认和审计。   

### 15.1 OpenAI 文档总映射

| OpenAI 官方文档及具体章节 | 官方能力 | 对应本文章节 | Link 中的采用方式 |
|----------------------------------|------------|------------------|-----------------------|
| [Create a model response / Responses API](https://developers.openai.com/api/reference/cli/resources/responses/methods/create) | 文本、图片、文件输入；会话；工具；流式和后台响应 | §5 产品形态、§12 工具、§13 Agent 架构 | 作为 OpenAI 供应商适配器的核心推理接口 |
| [Function calling — How it works](https://developers.openai.com/api/docs/guides/function-calling#how-it-works) | 模型生成函数调用名称和参数，由应用执行函数并回传结果 | §9 风险分级、§12 Agent 工具设计 | 实现强类型 Link 业务工具；模型不直接操作数据库或供应商 |
| [Structured model outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | 使模型输出符合给定 JSON Schema | §7 证据模型、§11 业务对象、§12 工具公共结构 | 约束 `ai_conclusion`、`action_request` 等输出；服务端仍需二次校验 |
| [File search — How to use](https://developers.openai.com/api/docs/guides/tools-file-search#how-to-use) | 从上传文件和向量库中进行语义与关键词检索，并返回文件引用 | §6 内容库、§7 依据、§13 上下文 | 可用于检索项目资料；必须按租户、项目、版本和有效期过滤 |
| [File search — Metadata filtering](https://developers.openai.com/api/docs/guides/tools-file-search#metadata-filtering) | 按文件元数据限制检索结果 | §6.4 内容与页面库、§13.4 多租户规则 | 元数据至少包含租户、项目、资料类型、版本、状态和生效期 |
| [MCP and Connectors — Approvals](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#approvals) | 通过连接器或远程 MCP 访问外部系统，并支持调用前批准 | §9 人工控制、§12.3 扩展工具、§17 外部系统 | 用于外部 Agent 或标准连接；Link 自身权限和确认网关不能省略 |
| [MCP and Connectors — Risks and safety](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#risks-and-safety) | 说明远程 MCP 可能接触和传出敏感上下文 | §13 多租户、§19 数据安全 | 只连接受信任 MCP；最小化上下文；记录实际外发字段 |
| [Background mode](https://developers.openai.com/api/docs/guides/background) | 异步执行长时间响应并轮询状态 | §5.4 AI 任务中心、§13.5 任务模型 | 可承载长摘要或大批资料检查；Link 任务表仍是业务状态来源 |
| [Model guidance](https://developers.openai.com/api/docs/guides/latest-model) | 模型选择、推理强度、工具调用和评测建议 | §14 模型路由、§18 容量、§22 验收 | 不把当前模型名称写死在业务代码；通过评测和路由配置选择 |
| [Data controls in the OpenAI platform](https://developers.openai.com/api/docs/guides/your-data) | API 数据使用、应用状态、监测日志和保留控制 | §19 数据与隐私 | 按使用的端点和功能逐项确认数据保留；企业合同与法务评审优先 |
| [Rate limits](https://developers.openai.com/api/docs/guides/rate-limits) / [Cost optimization](https://developers.openai.com/api/docs/guides/cost-optimization) | 供应商限额、吞吐和成本优化 | §18 容量、§22 系统验收 | 建立租户级限流、使用量记录、模型路由和预算预警 |
| [Safety best practices](https://developers.openai.com/api/docs/guides/safety-best-practices) | 上线前安全设计、测试和人工控制建议 | §9 风险分级、§19 安全 | 高风险对外内容人工审核，输入输出限制并开展对抗测试 |

### 15.2 Responses API 在 Link 中的责任

OpenAI Responses API 可以处理输入、生成响应、调用自定义工具或内置工具，并支持多轮状态、流式响应和后台执行。它适合作为 Link 的模型运行接口，但不应成为 Link 的业务数据库。

推荐调用关系：
```text
浏览器 AI 面板
→ Link Agent Gateway
→ 构建最小项目上下文
→ OpenAI Responses API
→ 返回文本、结构化结果或工具调用请求
→ Link 策略网关检查
→ 人员确认或预授权规则
→ Link 业务服务执行
→ 执行结果回传模型并写入 Link 审计
```

Link 必须自行保存：
- `agent_task_id` 和任务状态；
- 租户、项目、用户和对象权限快照；
- 使用的资料与版本；
- 模型返回的结构化草稿；
- 用户确认、修改或驳回；
- 实际业务执行结果；
- 外部供应商响应和异常。

OpenAI 的 `response_id`、`conversation` 或 `previous_response_id` 仅作为模型调用引用，不能替代上述业务记录。

### 15.3 Function calling 对应 Link 的受控执行

OpenAI 官方文档明确的工作方式是：模型返回工具调用，应用程序执行实际函数，再把结果返回给模型。由此可直接得出 Link 的实现边界：

| 环节 | OpenAI/模型负责 | Link 负责 |
|------|-------------------|-----------|
| 选择动作 | 根据上下文建议调用某个允许的工具 | 限定本次可见工具集合 |
| 生成参数 | 按工具 Schema 生成候选参数 | 验证类型、租户、项目、对象、版本和业务规则 |
| 执行动作 | 不直接执行 | Link 业务服务或连接器执行 |
| 处理结果 | 读取工具结果并继续生成解释或下一步 | 判断结果是否为权威事实并持久化 |
| 失败重试 | 可以提出重试建议 | 决定是否可重试、是否会重复写入以及如何补偿 |

因此，以下做法不允许：
- 把数据库连接、任意 SQL 或通用 HTTP 请求暴露成模型工具；
- 仅因为参数符合 JSON Schema 就直接执行；
- 由模型自行构造租户、项目或用户权限；
- 把工具调用请求误写成已发送、已发布或预约已确认；
- 对有副作用的工具进行无幂等保护的自动重试。

### 15.4 Structured Outputs 对应业务数据结构

OpenAI Structured Outputs 用于约束模型输出符合 JSON Schema，适合以下对象：
- 客户条件提取结果；
- 接待准备卡；
- 接待纪要草稿；
- AI 结论与证据引用；
- SMS 草稿风险检查；
- 工具调用前的 `action_request`；
- 归因或评分的解释结构。

示意结构：
```json
{
  "conclusion_type": "visit_preparation",
  "customer_id": "cus_internal_id",
  "facts": [],
  "customer_statements": [],
  "inferences": [],
  "evidence_ids": [],
  "source_versions": [],
  "needs_human_confirmation": true
}
```

结构化输出只能降低格式错误，不能证明内容真实。Link 仍要验证：
1. `customer_id` 是否属于当前项目；
2. `evidence_ids` 是否存在且用户有权查看；
3. 资料版本是否有效；
4. 枚举和状态转换是否符合业务规则；
5. 是否涉及对外发送或高风险承诺；
6. 是否需要人工确认。

### 15.5 File search 对应项目知识库

OpenAI File search 可以从向量库搜索已上传文件并生成带文件引用的回答。若采用该托管工具，建议每次检索至少限制：
```text
tenant_id
project_id
document_type
document_status = published
effective_from <= current_time
effective_to > current_time 或为空
language = ja / zh / en
```

资料入库流程：
```text
资料上传
→ 病毒与格式检查
→ 权限和项目归属
→ 生成资料版本
→ 审核并发布
→ 写入向量库与元数据
→ AI检索
→ 返回文件引用
→ 用户可打开 Link 中的原始资料版本
```

若企业不允许文件上传到外部托管向量库，则使用 Link 自建检索或企业专属向量库；模型只接收已经过滤后的必要片段。

### 15.6 MCP 对应外部 Agent 和系统连接

OpenAI MCP 文档说明远程 MCP 和连接器可以赋予模型访问外部服务的能力，并提供调用审批机制。VISTA Link 可以把自己的有限业务能力暴露为 MCP 工具，但建议分两种模式：

| 模式 | 场景 | 推荐控制 |
|------|------|------------|
| Link 调用外部 MCP | 获取日历、CRM 或企业资料 | 受信任服务器白名单、OAuth、最小字段、调用前批准 |
| 外部 Agent 调用 Link MCP | Codex 或企业 Agent 读取 Link、发起草稿或动作 | Link 认证、用户授权、项目范围、工具白名单、二次确认和审计 |

OpenAI 的 MCP approval 是额外防线，不替代 Link 自己的权限和业务确认。任何 `send`、`publish`、`hold_slot`、`confirm` 类型工具仍执行 §9 的风险分级。

### 15.7 Background mode 与浏览器任务中心

后台模式适用于可能持续数分钟的模型响应。Link 中可用于：
- 大项目资料一致性检查；
- 多客户接待准备的批量预生成；
- 历史页面版本比较；
- 大量行为记录摘要；
- 非实时的质量评测。

但浏览器任务中心不能直接依赖一次 HTTP 连接：
1. Link 先建立 `agent_task`；
2. 调用 OpenAI 后保存供应商响应 ID；
3. Worker 轮询或接收回调；
4. 将供应商状态映射为 Link 状态；
5. 浏览器通过 SSE/WebSocket 读取 Link 状态；
6. 任务完成后仍由 Link 保存业务草稿、确认和审计。

官方后台模式存在特定的数据暂存和保留行为，使用前需要结合企业数据要求审查；高敏感租户可以改用前台响应、专属策略或其他部署方式。

### 15.8 Codex 与 VISTA Link 的关系

Codex 的价值是提供一种可参考的 Agent 交互模式：理解上下文、拆解任务、调用工具、展示过程、等待批准、继续执行。VISTA Link 不应复制 Codex 的代码编辑、Shell 或本地文件系统能力。
```text
参考 Codex 的：任务体验、工具编排、过程可见、批准和恢复
不复制 Codex 的：代码工作区、通用 Shell、任意文件修改、开发者权限模型
Link 自己建设的：客户/页面/接待/SMS/预约对象、项目权限和业务审计
```

结论：面向企业客户的产品可以“像 Codex 一样工作”，但底层应以 Responses API、Function calling、MCP 和 Link 自己的业务服务组合，而不是把 Codex 客户端直接嵌入 Link。

### 15.9 数据、限流、成本和安全文档如何落地

OpenAI 官方数据控制文档说明 API 数据的使用与保留会受到所用功能和账户配置影响；因此不能只写一句“使用 OpenAI API”，而应在技术设计中建立逐功能清单：

| 功能 | 发送数据 | 是否保存供应商对象 | 保留/删除方式 | Link 替代方案 |
|------|------------|---------------------------|-------------------|-----------------|
| 普通 Responses 请求 | 最小任务上下文 | 按实际 `store` 和企业策略 | 以官方账户和端点规则为准 | 前台无状态请求或其他供应商 |
| Background mode | 长任务上下文 | 为异步执行存在必要暂存 | 按官方后台模式规则评审 | Link Worker 拆分为短请求 |
| File search | 上传文件和向量索引 | 存在文件与向量库对象 | 项目停用时执行删除流程 | Link 自建/企业向量库 |
| MCP/Connector | 发给 OpenAI 及目标服务的必要上下文 | 同时受 MCP 服务方规则影响 | 两端分别确认 | Link 直连接口 |

限流与成本方面，Link 的租户额度应低于供应商账户上限，并记录每次任务的输入、输出、缓存、工具调用和重试成本。供应商返回 429、超时或配额不足时，应进入备用模型、延迟队列或人工模式，而不是让浏览器无限重试。

安全方面，对外消息、价格政策、合同解释、批量操作和业务事实继续遵守 §9 的人工控制。稳定的最终用户标识应使用不可逆或隐私保护的内部映射，不直接发送姓名、邮箱或手机号作为供应商用户标识。

---

## 16\. DeepSeek API、DeepSeek Harness 官方文档与 Link 方案对应章节
> 名称说明：正确英文名称为 **DeepSeek**；本文保留用户常用的“DeepSeek Harness”表述。核对日期：2026-08-22。DeepSeek Harness 当前官方定位为 developer preview，架构和接口仍可能发生不兼容变化。   

### 16.1 DeepSeek 文档总映射

| DeepSeek 官方文档及具体章节 | 官方能力 | 对应本文章节 | Link 中的采用方式 |
|------------------------------------|------------|------------------|-----------------------|
| [Your First API Call](https://api-docs.deepseek.com/) | OpenAI/Anthropic 兼容形式的模型 API 接入 | §14 模型中立、§16.2 供应商适配 | 作为模型供应商之一，通过 Provider Adapter 接入 |
| [Tool Calls](https://api-docs.deepseek.com/guides/tool_calls) | 模型生成外部工具调用；应用负责执行；提供 strict 模式说明 | §9 风险、§12 工具设计 | 使用同一 Link 业务工具定义，但进行 DeepSeek 兼容测试 |
| [JSON Output — Notice](https://api-docs.deepseek.com/guides/json_mode/#notice) | 输出有效 JSON 的配置与限制 | §7、§11、§16.4 | 用于结构化草稿；不能等同于完整业务校验 |
| [Thinking Mode — Tool Calls](https://api-docs.deepseek.com/guides/thinking_mode#tool-calls) | 思考模式中的多轮工具调用及上下文传递要求 | §13.5 任务、§16.5 Adapter 状态 | 适配器保留供应商要求的消息字段，不在前端展示原始推理 |
| [Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat) | Chat API 本身无状态，调用方传递历史消息 | §13.5 任务模型 | Link 自己保存会话和上下文，按最小必要原则重建请求 |
| [Context Caching](https://api-docs.deepseek.com/guides/kv_cache/) | 对重复前缀进行缓存并返回命中统计 | §14 模型路由、§18 容量成本 | 通过稳定系统提示和资料前缀改善成本，但不依赖必然命中 |
| [Rate Limit & Isolation](https://api-docs.deepseek.com/quick_start/rate_limit/) | 账户并发、429 和 `user_id` 隔离参数 | §18 多用户容量 | 用于供应商限流适配；不能替代 Link 租户隔离 |
| [DeepSeek Harness developer preview](https://www.deepseek.com/harness/) | 插件化 Agent Harness、可追溯运行、Web UI 和多种运行模式 | §13 Agent 架构、§16.6 Harness 使用方式 | 作为运行时研究、企业专属部署候选或架构参考 |
| [DeepSeek Harness Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) | Cordis 插件系统，模型、工具、会话和 Agent Loop 可替换 | §13、§14 | 参考其插件化 Provider/Tool/Session 设计，不直接继承业务权限 |
| [Use the Web UI](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart) | 浏览器界面、工作区、任务和操作批准 | §5 浏览器产品形态 | 证明浏览器使用方式可行；Link 仍需自己的非技术业务界面 |
| [Python SDK](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md) | 通过 SDK 驱动 Harness 运行时和会话 | §16.6、§18 部署 | 适合原型、内部工具或隔离运行时评估，不作为首期必选依赖 |
| [Data Processing Statement](https://www.deepseek.com/harness/data-processing/) | 本地默认处理范围，以及外部模型、MCP、插件可能产生的数据外发 | §19 数据与隐私 | 建立逐工具数据流清单，不能只依据“本地优先”判断合规 |
| [Safe Use Policy](https://www.deepseek.com/harness/en/privacy/) | 本地执行、联网和不可信数据可能带来的安全风险；建议隔离环境 | §19 安全、§16.7 Harness 边界 | 若运行 Harness，必须使用容器/虚拟机、最小权限和网络白名单 |

### 16.2 DeepSeek API 作为模型供应商

DeepSeek API 可以通过兼容接口接入现有 SDK，但“接口形式兼容”不代表“功能和行为完全一致”。Link 的 Provider Adapter 需要统一以下内部契约：
```text
generate_text()
generate_structured_output()
request_tool_call()
continue_with_tool_result()
stream_events()
cancel_or_timeout()
report_usage()
normalize_error()
```

每次增加或升级 DeepSeek 模型时，至少验证：
- 日文客户沟通草稿质量；
- JSON/Schema 兼容性；
- 工具名称和参数遵循程度；
- 多轮工具调用；
- 流式事件格式；
- 超时、429、服务过载和重试行为；
- 上下文长度和截断；
- 缓存命中统计；
- 内容安全和敏感信息处理；
- 供应商数据政策。

### 16.3 Tool Calls 对应 Link 工具网关

DeepSeek 官方 Tool Calls 文档同样说明：模型输出调用请求，具体函数由使用方提供和执行。因此 OpenAI 与 DeepSeek 可以共享 §12 中的业务工具定义，但不能直接共享所有供应商请求体。

推荐结构：
```text
Link 标准工具 Schema
        ↓
Provider Adapter 转换
        ├─ OpenAI Function tool
        └─ DeepSeek Tool Calls
        ↓
供应商返回工具调用候选
        ↓
统一解析为 Link action_request
        ↓
Link 权限、风险、确认和幂等检查
        ↓
Link 业务服务执行
```

DeepSeek strict 模式可减少工具参数格式错误，但其使用范围和支持的 JSON Schema 特性需要单独验证。无论是否 strict，Link 都必须执行服务端权限和业务校验。

### 16.4 JSON Output 与 OpenAI Structured Outputs 的差异

两类能力不能简单视为同一等级：

| 项目 | OpenAI Structured Outputs | DeepSeek JSON Output | Link 统一处理 |
|------|-------------------------|--------------------|-----------------|
| 主要目标 | 按给定 JSON Schema 输出 | 输出有效 JSON 字符串 | 转换为内部 DTO |
| 约束强度 | 以官方支持的 JSON Schema 为准 | 官方说明需要提示中写明 JSON 和示例，并提示可能出现空内容 | 必须做字段、枚举、对象权限和事实验证 |
| 工具参数 | Function calling 可定义严格工具结构 | Tool Calls 有 strict Beta 模式 | 生产前做供应商契约测试 |
| 失败处理 | 解析失败、拒答、未完成分别处理 | 空内容、截断、JSON 解析失败分别处理 | 不允许失败结果进入业务写入 |

因此，Link 对外只暴露统一的 `ai_conclusion` 和 `action_request`，供应商差异封装在 Adapter 内部。

### 16.5 思考模式和多轮会话

DeepSeek 官方文档说明 Chat API 的多轮上下文由调用方管理；思考模式进行工具调用时，还存在需要正确传递相应消息字段的供应商要求。

Link 的处理方式：
1. Agent Task Service 保存标准化对话和工具事件；
2. DeepSeek Adapter 保存继续调用所需的供应商字段；
3. 上下文构建器决定哪些历史事实仍有效；
4. 对长期会话进行摘要或压缩，而不是无限发送全部历史；
5. 原始推理内容不作为销售端解释，也不当作业务审计依据；
6. 给用户展示的是证据、工具调用、输入资料版本和最终结论。

这可以避免把供应商内部推理与 Link 所要求的“可解释业务证据”混为一谈。

### 16.6 DeepSeek Harness 可以怎么使用

DeepSeek Harness 官方将其描述为本地优先、可扩展的 Agent 开发/运行环境，能力通过插件组合，并以追加式会话日志支持追踪、恢复、分叉、搜索和回放。

对 Link 有价值的参考包括：
- 模型、工具、会话、存储、Agent Loop 和 UI 可插拔；
- 单次运行过程可追踪；
- 支持 Web UI 和程序化 SDK；
- 能通过配置组合不同运行模式；
- 可以把供应商运行时部署在隔离环境。

推荐采用方式：

| 方案 | 建议 | 原因 |
|------|------|------|
| 直接把 Harness Web UI 给销售使用 | 不采用 | 面向开发者和代码工作区，业务语言、权限和交互不符合销售场景 |
| 把 Harness 作为 Link 的唯一后端 | 暂不采用 | 当前为 developer preview，且 Link 仍需完整业务层和多租户治理 |
| 用 Harness 做内部原型和工具编排验证 | 可以 | 快速验证 Agent Loop、插件和可追溯体验 |
| 企业专属隔离运行时 | 条件采用 | 客户要求本地/专属运行且完成安全、兼容和运维评估后 |
| 借鉴其插件架构 | 采用 | 与 Link 模型中立、工具中立和会话可追溯目标一致 |

### 16.7 DeepSeek Harness 的安全和数据边界

“本地优先”不等于“所有数据永不离开环境”。DeepSeek Harness 数据处理说明明确提示：当调用外部模型、网络工具、MCP 或插件时，数据可能由相应服务方处理。因此需要建立以下清单：

| 数据流 | 必须记录 |
|---------|------------|
| Harness → 模型 API | 发送的客户字段、资料片段、模型供应商和区域 |
| Harness → MCP/插件 | 工具名称、参数、目标服务器、授权用户和返回结果 |
| Harness 本地存储 | 会话、工具日志、附件、文件路径、凭据和保存期限 |
| 遥测/诊断 | 是否开启、字段范围、脱敏方式和接收地址 |

若 Harness 获得 Shell 或文件编辑能力，必须在专用容器或虚拟机中运行，并实施：
- 非 root 用户；
- 只挂载明确工作目录；
- 禁止访问 Link 生产数据库；
- 外连网络白名单；
- 临时凭据和密钥代理；
- CPU、内存、运行时间和进程数限制；
- 会话结束后的工作区清理；
- 工具调用与文件变化审计。

对于 VISTA Link 的常规销售 Agent，推荐完全不暴露 Shell 和通用文件编辑工具，只暴露 §12 的业务工具。

### 16.8 OpenAI 与 DeepSeek 的统一选择原则
```mermaid
flowchart LR
    A["Link浏览器AI"] --> B["Agent Gateway"]
    B --> C["统一上下文与任务"]
    C --> D["Provider Adapter"]
    D --> E["OpenAI Responses API"]
    D --> F["DeepSeek API"]
    D -. 企业专属候选 .-> G["隔离的DeepSeek Harness运行时"]
    E --> H["标准化文本 / 结构化结果 / 工具调用"]
    F --> H
    G --> H
    H --> I["Link策略与权限网关"]
    I --> J["Link强类型业务工具"]
    J --> K["客户 / 页面 / SMS / 预约 / 归因"]
    K --> L["统一结果与审计"]
    L --> A
```

| 维度 | OpenAI 路径 | DeepSeek 路径 | Link 决策原则 |
|------|-------------|---------------|-----------------|
| 核心 API | Responses API | Chat/兼容 API；按当期能力评估 | 通过 Provider Adapter 隔离 |
| 工具调用 | Function calling、MCP | Tool Calls；Harness 插件工具 | 统一转成 Link action\_request |
| 结构化输出 | JSON Schema Structured Outputs | JSON Output、strict Tool Calls | 统一 DTO 和服务端校验 |
| 长任务 | Background mode | Link 自己的队列/Worker；Harness 会话 | Link 任务状态始终为主 |
| 知识检索 | File search 或外部检索 | Link 自建检索、Harness 插件或兼容能力 | 先按租户/项目过滤再给模型 |
| 浏览器体验 | Link 自建 UI | Harness 有开发者 Web UI | 销售端统一使用 Link UI |
| 本地/专属运行 | 取决于模型和企业方案 | Harness 提供本地优先运行时参考 | 按客户合规和运维成本选择 |
| 切换方式 | OpenAI Adapter | DeepSeek Adapter | 业务对象、工具和审计不随供应商变化 |

模型供应商的最终选择不能只看单次价格或演示效果。应使用同一批日文销售任务、相同证据和相同工具 Schema，对质量、延迟、成本、格式遵循、工具成功率和数据政策进行评测。

---

## 17\. 外部系统集成

### 17.1 统一集成层

所有 CRM、预约、日历、广告和交易系统通过统一接口层连接：
```mermaid
flowchart LR
    subgraph EXT["外部权威系统"]
        A["CRM"]
        B["预约 / 日历"]
        C["SMS / LINE / 邮件"]
        D["广告 / 活动"]
        E["交易 / 合同 / 财务"]
    end

    subgraph HUB["Link统一集成层"]
        F["API与Webhook"]
        G["身份和字段映射"]
        H["幂等、重试和冲突规则"]
        I["同步日志与告警"]
    end

    subgraph LINK["VISTA Link业务层"]
        J["客户与内容"]
        K["访问与分享"]
        L["AI任务与行动"]
        M["结果、归因与审计"]
    end

    A <--> F
    B <--> F
    C <--> F
    D <--> F
    E <--> F
    F --> G
    G --> H
    H --> I
    H <--> J
    H <--> K
    H <--> L
    H <--> M
```
- 标准 API；
- Webhook；
- 外部 ID 与 Link ID 映射；
- 字段映射；
- 幂等和重复事件处理；
- 失败重试；
- 冲突规则；
- 同步日志和告警；
- 权限和个人信息最小化。

### 17.2 推荐接入顺序
1. CSV 导入导出和人工兜底；
2. SMS 供应商；
3. 预约/日历系统；
4. 主要 CRM；
5. 广告与活动数据；
6. 交易系统必要结果；
7. LINE/邮件等更多触达渠道。

### 17.3 主数据归属

| 数据 | 推荐权威来源 |
|------|------------------|
| 项目内容、页面和访问行为 | VISTA Link |
| 客户基本资料与负责人 | 项目确定 Link 或 CRM 中的一方为主 |
| 通信同意与退订 | 实际发送平台与 Link 同步，取更严格状态 |
| 可预约时段和预约确认 | 预约/日历系统 |
| 实际到访 | 预约系统、门店系统或有权限人员 |
| 认购、签约、金额 | CRM/交易/合同系统 |
| 活动成本 | 广告或财务系统 |
| 归因、内容效果和 AI 工作记录 | VISTA Link |

---

## 18\. 服务器要求与多 B 端用户方案

### 18.1 推荐部署方式

使用模型 API 时，Link 服务器不运行大模型，主要承担鉴权、上下文、任务队列、工具调用、数据库和连接器。服务器要求远低于自建大模型，不需要在初期配置 GPU。

### 18.2 起步配置建议

| 阶段 | 参考规模 | 推荐起步资源 | 说明 |
|------|------------|------------------|------|
| 企业试点 | 1—3 个项目、约 50 名用户 | 2 个应用实例，各 2—4 vCPU/4—8 GB；托管 PostgreSQL；Redis；对象存储 | 保证高可用和可回滚 |
| 商业初期 | 10—30 个租户、数百用户 | 3—6 个无状态应用实例；独立 Worker；托管数据库高可用；队列与集中日志 | 按任务类型和租户限流 |
| 规模化 | 数千月活、数百并发任务 | 应用、Agent Worker、连接器 Worker 分池；数据库读副本/分区；自动扩缩容 | 容量以并发任务而非注册用户数估算 |
| 企业专属 | 单一大型客户 | 专属命名空间、数据库或密钥，必要时专属 Worker | 满足隔离和合规要求 |

实际容量必须通过压测验证。决定扩容的关键指标包括：
- 同时运行的 Agent 任务数；
- 单任务平均模型调用次数和耗时；
- 上下文大小；
- 外部连接器延迟；
- 队列等待时间；
- 数据库慢查询；
- 每租户高峰发送量。

### 18.3 多租户公平性
- 每租户并发上限；
- 每用户短时限流；
- 交互任务优先于批处理；
- 对外发送与内部分析分队列；
- 大任务分片并设置最大执行时间；
- 单租户异常不能占满全部 Worker；
- 额度不足时给出明确提示，不把失败伪装成模型无回答。

---

## 19\. 可靠性、安全与日本合规准备

### 19.1 可靠性
- 所有写入和外部动作使用幂等键；
- 页面、消息和关键记录使用乐观锁或版本号；
- 模型调用可以重试，业务写入不能盲目重试；
- 外部系统超时后先查询状态，再决定是否补偿；
- 发送失败、预约冲突和发布失败保留人工处理入口；
- AI 不可用时，原有确定性页面与业务流程继续工作。

### 19.2 数据与隐私
- AI 只获得完成当前任务所需的最少数据；
- 跨项目数据不得进入提示、检索结果或日志；
- 联系方式、家庭和财务相关字段按角色脱敏；
- 资料请求、物件登记、预约和问卷在提交前显示个人信息利用目的，并保存当时展示的文本版本；
- 通信许可按邮件、LINE、SMS、电话等渠道分别保存，退订或更严格状态优先；
- 客群标准方案只表示本次接待或培育路径，不自动写成客户永久属性；AI 推测的家庭、购买能力、资产目的不得覆盖客户明确表达；
- 原始行为数据、AI 工作记录和业务审计分开存储；
- 外部模型的数据处理区域、保留策略和训练使用政策应纳入供应商评审；
- 日本个人信息使用目的、保存期限、第三方提供和跨境处理需法务确认；实现基线参考[日本个人信息保护委员会通则指南](https://www.ppc.go.jp/personalinfo/legal/guidelines_tsusoku/)。

### 19.3 零容忍事件
- 跨租户或跨项目数据泄露；
- 未经授权发布或发送；
- 重复 SMS；
- 把“点击预约”显示为“预约成功”；
- 把 AI 推断显示为到访、认购、签约事实；
- 使用过期价格、优惠、合同或交付资料对外承诺；
- 审计记录无法还原实际发送版本和确认人。

---